.\" This man page is Copyright (C) 2003, 2010 Lennert Buytenhek.
.\" Permission is granted to distribute possibly modified copies
.\" of this page provided the header is included verbatim,
.\" and in case of nontrivial modification author and date
.\" of the modification is added to the header.
.TH iv_fd 3 2010-08-15 "ivykis" "ivykis programmer's manual"
.SH NAME
iv_fd_register, iv_fd_register_try, iv_fd_unregister, iv_fd_registered, iv_fd_set_handler_in, iv_fd_set_handler_err, iv_fd_set_handler_out \- deal with ivykis file descriptors
.SH SYNOPSIS
.B #include <iv.h>
.sp
.nf
struct iv_fd {
        int             fd;
        void            *cookie;
        void            (*handler_in)(void *);
        void            (*handler_out)(void *);
        void            (*handler_err)(void *);
};
.fi
.sp
.BI "void IV_FD_INIT(struct iv_fd *" fd ");"
.br
.BI "void iv_fd_register(struct iv_fd *" fd ");"
.br
.BI "int iv_fd_register_try(struct iv_fd *" fd ");"
.br
.BI "void iv_fd_unregister(struct iv_fd *" fd ");"
.br
.BI "int iv_fd_registered(const struct iv_fd *" fd ");"
.br
.BI "void iv_fd_set_handler_in(struct iv_fd *" fd ", void (*" handler ")(void *));"
.br
.BI "void iv_fd_set_handler_out(struct iv_fd *" fd ", void (*" handler ")(void *));"
.br
.BI "void iv_fd_set_handler_err(struct iv_fd *" fd ", void (*" handler ")(void *));"
.br
.SH DESCRIPTION
The functions
.B iv_fd_register
and
.B iv_fd_unregister
register, respectively unregister, a file descriptor with the current
thread's ivykis event loop.  Calling
.B iv_fd_registered
on a file descriptor returns true if that file descriptor is currently
registered with ivykis.
.PP
When a file descriptor that is registered with ivykis becomes ready for
input or output, or an error condition occurs on that file descriptor,
and a callback function for that event has been specified, that
callback function will be called in the thread that the file descriptor
was registered in.
.PP
And conversely, when a file descriptor that is already ready for input
or output or already has an error condition set is registered with
ivykis, and the corresponding callback function pointer is not NULL,
the callback function will be called in the next iteration of the
current thread's ivykis event loop.
.PP
Before a file descriptor is registered, it must have been
initialised by calling
.B IV_FD_INIT
on it, and must have had its
.B ->fd
member field set to a valid OS file descriptor.  The
.B ->handler_in, ->handler_out
and
.B ->handler_err
member fields point to callback functions that are to be called when
the specified file descriptor becomes ready for input or output or an
error condition occurs.  If any handler function is set to
.B NULL,
it indicates that the application is not interested in being notified
of the corresponding event.
.PP
An application is not allowed to change the
.B ->fd
member while a file descriptor is registered.
.PP
.B iv_fd_set_handler_in
changes the callback function to be called when descriptor
.B fd
becomes ready for input.  An application is not allowed to directly
change the
.B ->handler_in
member after the file descriptor has been registered, this function
has to be used instead.  Conversely, it is not allowed to use this
function before the file descriptor has been registered.
.PP
.B iv_fd_set_handler_out
is analogous to
.B iv_fd_set_handler_in,
only it deals with the callback function for output readiness
.B (->handler_out).
.PP
.B iv_fd_set_handler_err
is analogous to
.B iv_fd_set_handler_in
and
.B iv_fd_set_handler_out,
only it deals with the callback function for error conditions
.B (->handler_err).
.PP
When a handler function was NULL, and was set to a non-NULL value
by calling
.B iv_fd_set_handler_in, iv_fd_set_handler_out
or
.B iv_fd_set_handler_err,
and the file descriptor was already ready for input or output, or
already had an error condition set, an event is generated, and the
specified callback function will be called in the next iteration of
the current thread's event loop.  The application does not need to
poll the file descriptor to see if a condition was already raised.
.PP
Callback functions are passed a
.B cookie
value as their first and sole argument.  If the application wishes to
use this facility for transferring data to the callback function, it
should set the
.B ->cookie
member of a file descriptor to a value of type
.B void *.
This value can be modified directly by the application at any time
without calling a helper function.
.PP
When a file descriptor is registered with ivykis, it is transparently
set to nonblocking mode, and configured to be closed on
.BR exit (3).
.PP
An application is allowed to unregister a file descriptor from within
any callback function, including callback functions triggered by that
file descriptor itself, and even to free the memory corresponding to
that file descriptor from any callback function, but a
.B struct iv_fd
can only be unregistered in the thread that it was registered from.
.PP
It is allowed to register the same underlying OS file descriptor in
multiple threads, but a given
.B struct iv_fd
can only be registered in one thread at a time.
.PP
.B iv_fd_register
does not return errors to the caller, and in case of an error while
registering the file descriptor, for example if it isn't open or is
unpollable,
.BR iv_fatal (2)
will be invoked.  If it is not known whether registering the file
descriptor with the kernel will be successful or not, use
.B iv_fd_register_try
instead, which is a variant on
.B iv_fd_register
which returns a nonzero value in case of a registration error.
Since
.B iv_fd_register_try
disables various internal optimisations, it is recommended to use
.B iv_fd_register
whenever possible.
.PP
See
.BR iv_examples (3)
for programming examples.
.SH "SEE ALSO"
.BR ivykis (3),
.BR iv_examples (3)
